~ chicken-core (chicken-5) /manual/Extension tools
Trap1[[tags: manual]]2[[toc:]]34== Extension tools56The basic tools to install, uninstall and view "eggs" and the extensions7are {{chicken-install}}, {{chicken-uninstall}} and {{chicken-status}}.89{{chicken-install}} can be used in two modes: first, as a simple package10manager that downloads publicly available eggs (and their dependencies, if11necessary) and compiles the contained extensions, installing them on12a user's system.1314For development of eggs, {{chicken-install}} can also be invoked15without arguments, in a directory that contains an egg specification16file and the associated source code, building all components and17installing them.1819{{chicken-status}} simply lists installed eggs, the contained extensions,20and optionally the files that where installed with a particular egg.2122Below you will find a description of the available command line options23for all three programs. A specification of the egg description file24format is [[Egg specification format|here]].2526=== Security2728When eggs are downloaded and installed one is executing code29from potentially compromised systems. This applies also when30{{chicken-install}} executes system tests for required eggs. As31the code has been retrieved over the network effectively untrusted32code is going to be evaluated. When {{chicken-install}} is run as33''root'' the whole system is at the mercy of the build instructions34(note that this is also the case every time you install software via35{{sudo make install}}, so this is not specific to the CHICKEN36egg mechanism).3738Security-conscious users should never run {{chicken-install}} as root.39A simple remedy is to keep the repository inside a user's home40directory (see the section "Changing repository location" below).41Alternatively obtain write/execute access to the default location of the repository42(usually {{/usr/local/lib/chicken}}) to avoid running as43root. {{chicken-install}} also provides a {{-sudo}} option to perform44the last installation steps as root user, but do building and other45.setup script processing as normal. A third solution is to46override {{VARDIR}} when building the system47(for example by passing {{"VARDIR=/foo/bar"}} on the make command line,48or by modifying {{config.make}}. Eggs will then be installed in49{{$(VARDIR)/chicken/8}}.5051=== Changing the repository location5253When CHICKEN is installed a repository for eggs is created and initialized54in a default location (usually something like {{/usr/local/lib/chicken/9/}}).55It is possible to keep an egg repository in another location. This can be56configured at build-time by passing {{VARDIR=<directory>}} to {{make(3)}}57or by modifying the {{config.make}} configuration file. If you want to58override this location after chicken is installed, you can create a59repository directory, set the60{{CHICKEN_INSTALL_REPOSITORY}} and/or {{CHICKEN_REPOSITORY_PATH}}61environment variables to the full path of the new reopsitory and copy all files62from the default repository into the new one.6364Note that your binary version can differ from the one given in65the examples here, if your66chicken version is older or newer than the one used in these examples.67Check your default location for the correct binary-version number.6869{{CHICKEN_REPOSITORY_PATH}} is a directory (or a list of directories70separated by {{:}}/{{;}}) where eggs are to be71loaded from for all chicken-based programs. {{CHICKEN_INSTALL_REPOSITORY}}72is the place where eggs will be installed and which the egg-related73tools like {{chicken-install}}, {{chicken-uninstall}} and74{{chicken-status}} consult and update.7576Finally, {{CHICKEN_INSTALL_PREFIX}} allows you to override where any77installed files should be stored, including extension libraries, programs78and data files. Effectively this variable overrides the installation79prefix given when building and installing chicken. When installing eggs,80the location where dependency extensions and tools are installed will81not be automatically found, so setting this variable usually only makes82sense when used in combination with {{CHICKEN_REPOSITORY_PATH}}.8384{{CHICKEN_INSTALL_PREFIX}} is intended for special situations and should be used85with care. It is a last-resort utility to customize where build-results are placed.8687Make sure the paths given in these88environment variables are absolute and not relative.8990=== Static linking9192Static linking of extensions and programs is fully supported and93should be transparent to the user. Every extension will by94default be compiled into a dynamically loadable and a statically95linkable entity. By passing {{-static}} on the {{csc}} command-line,96eggs that are available in static form will be linked instead of97the dynamically loadable version. Use the {{linkage}} egg98description property to select in what modes a component should99be built.100101To identify the necessary object files during linking of102extensions, {{csc}}103creates so-called "link files" and installs them along the104statically compiled object file in the local egg repository.105These link files specify what objects should be linked when106an application is using a static variant of an extension.107108109=== Locations110111For experimentation or in-house builds of software it may be112useful to have private egg repositories in addition to the113official CHICKEN egg repository. This can be accomplished by114defining so-called "locations", directories that contain egg115source-code and description files and which should be scanned116before trying to retrieve an egg via the network.117118The file {{<PREFIX>/share/chicken/setup.defaults}} holds various119parameters that define where eggs should be downloaded, together120with more obscure options, and can be used to customize the121sources where eggs will be retrieved from. Adding a line of122the form123124{{(location "<PATH>")}}125126will add {{<PATH>}} as an additional egg source, where {{<PATH>}}127should be a directory in the local filesystem that contains128any number of eggs, one directory for each, including the source code129and the {{.egg}} files for each egg.130131Locations are searched before trying to retrieve from the network.132Any number of locations may be defined.133134135=== The egg cache136137Eggs are downloaded and built in the so called "egg cache", an138intermediate location used for storing already downloaded source code139and for providing a temporary location for building the eggs before140they are installed.141142By default the cache is located in the directory143{{.chicken-install/cache}} in the user's home directory ({{$HOME}} on144UNIX, or {{%USERPROFILE%}} on Windows. If the respective environment145variable is not set, then {{/tmp}} or {{/Temp}} is used.146147Built extensions and programs remain in the cache, to avoid rebuilding148already compiled code and multiple downloads of eggs in case the149installation of an egg fails - the dependencies will be cached after150the first download and re-download is not needed.151152{{chicken-install}} tries to take extreme care to avoid stale binaries,153but should you be in doubt, simply delete the directory, or run154{{chicken-install -purge}} to clear the cache or parts of it.155156You can override the location of the cache by setting the157{{CHICKEN_EGG_CACHE}} environment variable.158159160=== Egg installation in detail161162==== Retrieval163164First the egg names given on the command line (or, if no arguments165are given, all eggs identified by {{.egg}} files in the current166directory, including any in a subdirectory named {{chicken}})167must be retrieved, either from a local source or from the official168egg repository. Should the egg exist in the egg cache we check169whether this cached version is out of date. A cached egg is170considered out of date, if a) it is locally available and all cached171files belonging to the egg do not have newer timestamps than the172local files, or b) if it is a remotely retrieved egg and no173newer versions exist on the remote egg server and the last time174the cache was filled from the remote location is not later than175one hour. Additionally, if any changes in certain environment176variables that may influence the compilation of an egg, or if177the CHICKEN version changed, then retrieval of the egg sources178is enforced in any case.179180If the egg is in the current directory, or in181a "location" (as described above), the files are copied into182the cache. If the egg is remotely available, then it is retrieved183via HTTP from one of the egg servers defined in {{setup.defaults}}.184185Once the egg sources are retrieved and stored in the cache,186their {{.egg}} files are loaded and validated. After this187any egg dependencies are resolved and located in the cache,188triggering a recursive retrieval, if necessary.189190==== Preparation191192Unless the {{-retrieve}} option was given, the eggs intended193to be built and installed are now scheduled for compilation.194The egg information from the {{.egg}} files is processed and195translated into build and install scripts for the current196platform - if this CHICKEN was configured for cross compilation,197and no separate host- or target-build was selected, two sets198of build/install scripts will be generated, one for the host199system and one for the target.200201==== Building and installation202203Unless {{-dry-run}} was given on the command-line, the build-204and install scripts are now executed, ordered by the dependency205relationships between the full set of eggs that are scheduled206for compilation. If the {{-test}} option was given and a file named207{{run.scm}} exists in the {{tests}} subdirectory of the egg208sources, then this script is executed. Should it terminate with209an error or a non-zero exit code, the installation is still performed210and {{chicken-install}} does not abort. Only after all scheduled211eggs have been installed, {{chicken-install}} will terminate212with a non-zero exit code.213214Note that the build process attempts to minimize re-building215of already compiled files in the cache, using the {{chicken-do}}216program. See the manual page for {{chicken-do}} for more details.217218From the egg-information in the {{.egg}} file, the set of files219installed for a particular egg are added to the egg-information220and stored together with the build-artifacts produced by the221build scripts.222223=== chicken-install reference224225Available options:226227; {{-h -help}} : show this message and exit228; {{-version}} : show version and exit229; {{-force}} : don't ask, install even if versions don't match230; {{-k -keep}} : keep temporary files231; {{-s -sudo}} : use external command to elevate privileges when installing or removing files232; {{-no-install-dependencies}} : do not install dependencies233; {{-r -retrieve}} : only retrieve egg into cache directory, don't install (giving {{-r}} more than once implies {{-recursive}})234; {{-recursive}} : if {{-retrieve}} is given, retrieve also dependencies235; {{-dry-run}} : do not build or install, just print the locations of the generated build + install scripts236; {{-list-versions}} : list available version for an extension (HTTP transport only)237; {{-n -no-install}} : do not install, only build the egg.238; {{-purge}} : remove cached files for given eggs (or purge cache completely)239; {{-cached}} : install from cache, do not download240; {{-host}} : when cross-compiling, compile egg for host only241; {{-target}} : when cross-compiling, compile egg for target only242; {{-test}} : run included test-cases, if available243; {{-u -update-db}} : update export database244; {{-repository}} : print path to egg repository245; {{-override FILENAME}} : override versions for installed eggs with information given in {{FILENAME}}, which can be generated by {{-scan}} or by the {{-list}} option of the {{chicken-status}} program246; {{-from-list FILENAME}} : install eggs given in {{FILENAME}}, in the same format as produced by the {{-list}} option in {{chicken-status}}; this option may be given multiple times247; {{-v -verbose}} : be verbose248; {{-D -feature NAME}} : defines a build feature, that can be tested using {{cond-expand}} in egg specifications249; {{ -defaults FILENAME }} : use {{FILENAME}} as defaults instead of the installed {{setup.defaults}} file250251{{chicken-install}} recognizes the {{SUDO}}, {{http_proxy}} and {{proxy_auth}} environment variables, if set.252253When running {{chicken-install}} with an argument {{NAME}}, for which254no associated {{.egg}} file exists, then it will try to download the255extension via HTTP from the CHICKEN code repository at256[[http://code.call-cc.org/svn/chicken-eggs/]]. Extensions that are257required to compile and/or use the requested extension are downloaded258and installed automatically.259260261=== chicken-uninstall reference262263; {{-h -help}} : show usage information and exit264; {{-version}} : show version and exit265; {{-force}} : don't ask, delete whatever matches266; {{-match}} : treat egg-names as glob patterns267; {{-s -sudo}} : use external command to elevate privileges for deleting files268; {{-host}} : when cross-compiling, remove eggs for host system only269; {{-target}} : when cross-compiling, remove eggs for target system only270271272=== chicken-status reference273274; {{-h -help}} : show usage information and exit275; {{-version}} : show version and exit276; {{-f -files}} : list installed files277; {{-match}} : treat egg-names as glob patterns278; {{-host}} : when cross-compiling, show eggs for host system only279; {{-target}} : when cross-compiling, show eggs for target system only280; {{-list}} : list installed egg version in format suitable for {{chicken-install -override}} or {{-from-list}}281; {{-c -components}} : list installed components282; {{-cached}} : list eggs available in the cache directory283284285---286287Previous: [[Extensions]]288289Next: [[Egg specification format]]